package org.marketlive.entity.attributes;

/*
(C) Copyright MarketLive. 2006. All rights reserved.
MarketLive is a trademark of MarketLive, Inc.
Warning: This computer program is protected by copyright law and international treaties.
Unauthorized reproduction or distribution of this program, or any portion of it, may result
in severe civil and criminal penalties, and will be prosecuted to the maximum extent
possible under the law.
*/

import java.util.List;

/**
 * Provides creators and accessors for <code>IAttribute</code> entities.
 */
public interface IAttributeHome extends IEntityHome {

    /**
     * Persists a new instance of the given object and returns its primary key.
     *
     * @param objectDO an <code>AttributeDO</code> or <code>AttributeTypeDO</code> with all values populated except the AttributeDO's identifier
     * @return the primary key of the new object
     * @throws Exception if an error occurs. The specific exception is caught at the DAO level.
     * @see com.marketlive.entity.attributes.AttributeDO
     */
    public int insert(Object objectDO) throws Exception;

    /**
     * Returns <code>IAttribute</code>s or <code>IAttributeType</code>s with the given levelID and levelType.
     * The implementation determines whether the collection contains Attributes or AttributeTypes.
     *
     * @param levelID the primary key of the object to find the attribute for. If searching
     *        levelType Product, for example, levelID is the key of the product to find
     *        attributes for.
     * @param levelType usually one of the following: <code>Product</code>, <code>Sku</code>,
     *        or <code>Category</code>
     * @return a collection of <code>IAttribute</code>s or <code>IAttributeType</code>s
     * @throws Exception if an error occurs
     */
    public List findByLevel(Integer levelID, String levelType) throws Exception;

    /**
     * Returns <code>IAttribute</code>s or <code>IAttributeType</code>s with the given levelIDs and levelType.
     * The implementation determines whether the collection contains Attributes or AttributeTypes.
     * For example, if searching levelType <code>Sku</code> and levelIDs [1,2,3], attributes for SKUs with
     * IDs 1, 2, and 3 are returned.
     *
     * @param levelIDs the identifiers of the entities to retrieve attributes for
     * @param levelType usually one of <code>Product</code>, <code>Sku</code>, or <code>Category/PGroup</code>
     * @return a collection of <code>IAttribute</code>s or <code>IAttributeType</code>s
     * @throws Exception if an error occurs
     */
    public List findByLevel(Integer[] levelIDs, String levelType) throws Exception;

    /**
     * Returns <code>IAttribute</code>s or <code>IAttributeType</code>s for the given ID, category type, and attribute
     * type.
     * For example, if searching for levelID 8, levelType <code>Category</code>, and type <code>Checkbox</code>, returns
     * all the checkbox attributes for the category with ID 8.
     *
     * @param levelID the identifier of the entity to retrieve attributes for
     * @param levelType usually one of <code>Product</code>, <code>Sku</code>, or <code>Category/PGroup</code>
     * @param type the type of attributes to retrieve; for example, checkbox, list, or text
     * @return a collection of <code>IAttribute</code>s or <code>IAttributeType</code>s
     * @throws Exception if an error occurs
     */
    public List findByLevelAndType(Integer levelID, String levelType, String type) throws Exception;

    /**
     * Returns <code>IAttribute</code>s with the given levelType.
     *
     * @param levelType the type of attributes to find, usually <code>Category</code>, <code>Product</code>,
     * or <code>Sku</code>
     * @return a collection of attributes for the given <code>levelType</code>
     * @throws Exception if an error occurs
     */
    public List findByLevelType(String levelType) throws Exception;

    /**
     * Returns <code>IAttribute</code>s with the given levelType.
     * This method is not used in the default implementation.
     *
     * @param levelType usually one of <code>Product</code>, <code>Sku</code>, or <code>Category/PGroup</code>
     * @param validData if true, returns only valid records
     * @return a collection of attributes for the given <code>levelType</code>
     * @throws Exception if an error occurs
     */
    public List findByLevelType(String levelType, boolean validData) throws Exception;

    /**
     * Returns <code>IAttribute</code>s or <code>IAttributeType</code>s in the given category.
     * The implementation determines whether the collection contains Attributes or AttributeTypes.
     *
     * @param category the user-defined attribute category
     * @return a collection of attributes for the given category
     * @throws Exception if an error occurs
     */
    public List findByCategory(String category) throws Exception;

    /**
     * Returns <code>IAttribute</code>s or <code>IAttributeType</code>s in the given category for the given ID
     * and of the given type. For example, searching for a category named <code>Images</code>, levelID 3, and levelType
     * <code>Sku</code> would return Images attributes for the SKU with ID 3.
     * The implementation determines whether the collection contains Attributes or AttributeTypes.
     *
     * @param category the user-defined attribute category
     * @param levelID the identifier of the entities to retrieve attributes for
     * @param levelType usually one of <code>Product</code>, <code>Sku</code>, or <code>Category/PGroup</code>
     * @return a collection of <code>IAttribute</code>s or <code>IAttributeType</code>s
     * @throws Exception if an error occurs
     */
    public List findByCategoryAndLevel(String category, Integer levelID, String levelType) throws Exception;

    /**
     * Updates the given attributeList in the persistent store.
     *
     * @param attributeList the <code>AttributeDO</code>s or <code>AttributeTypeDO</code>s to update
     * @return the number of records updated, or 0 if the operation failed
     * @throws Exception if an error occurs
     */
    public int updateAll(List attributeList) throws Exception;

    /**
     * Returns a new <code>IAttribute</code>.
     *
     * @return an attribute
     */
    public IAttribute getAttributeDO();

    /**
     * Returns a new <code>IAttribute</code>.
     *
     * @param iAttributeType the type of attribute to return
     * @return an attribute
     */
    public IAttribute getAttributeDO(IAttributeType iAttributeType);

    /**
     * Returns an attribute key with the given level, levelID, and typeID.
     *
     * @param level the level of the attribute
     * @param levelID the levelID of the attribute
     * @param typeID the typeID of the attribute
     * @return the attribute key
     */
    public IAttributeKey getAttributeKey(String level, Integer levelID, Integer typeID);

    /**
     * Returns an attribute with the given level, levelID, and typeID.
     *
     * @param level the level of the attribute
     * @param levelID the levelID of the attribute
     * @param typeID the typeID of the attribute
     * @return the attribute
     */
    IAttribute getAttributeDO(String level, Integer levelID, Integer typeID);

}
